home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / graphics / bgires.zip / BGIRES.DOC next >
Text File  |  1994-06-03  |  8KB  |  179 lines
  1. BGIRES version 1.0 - TP 6.0 unit to store .BGI files in a resource file.
  2.  
  3.   Written for the public domain by D.J. Murdoch, July, 1992
  4.  
  5. Description:
  6.  
  7.   Graphics programs written in Borland languages can take advantage of
  8.   "BGI" drivers - Borland's standard graphics interface.  This lets them
  9.   be nearly device independent, since all driver-specific code is kept
  10.   in the .BGI files, and a standard interface is used to access it.
  11.  
  12.   When you want to distribute one of these programs, one option is to
  13.   distribute multiple .BGI files with your program - but that's messy.
  14.   You also have the option of linking several of them into the .EXE
  15.   file.  (Turbo Pascal comes with instructions on how to do this;
  16.   Borland even provides a BGILINK.MAK makefile to automate it for you,
  17.   in TP 6.0.) The trouble with this option is that the BGI drivers can't
  18.   be overlaid, so they take up valuable RAM space.  Since you only ever
  19.   need one of them, that's a waste.
  20.  
  21.   BGIRES offers a solution to these problems.  It lets you put the .BGI
  22.   files into a "resource file", and only load one of them from there
  23.   into RAM.  Since TP 6.0 allows you to attach a resource file to your
  24.   .EXE file, this is the best of both worlds:  you distribute only one
  25.   file, and only one BGI driver takes up RAM space.
  26.  
  27. Interfaced Procedures and Functions
  28.  
  29.   procedure ResInitGraph(var graphdriver,graphmode:integer;
  30.                          var resfile:TResourcefile;
  31.                          pathtodriver:string);
  32.  
  33.   Attempts to load the given driver (which may be Detect) from the
  34.   resource file, register it, and call initgraph.  PathToDriver will
  35.   only be used if the driver isn't in the resource file.
  36.  
  37.   function PutDriver(filename:string;var resfile:TResourcefile;
  38.                      keep:boolean):integer;
  39.  
  40.   Puts driver 'filename' into the given resource file.  If keep is true,
  41.   leaves it loaded in memory.  If keep is false, deletes it from memory.
  42.   Unfortunately, this leaves Graph thinking it's still there, and is
  43.   rather dangerous.  I think it would be safe to set keep to false if it
  44.   didn't correspond to the current graphics hardware, but I'm not sure.
  45.  
  46.   Returns a graphics error constant if something goes wrong.
  47.  
  48.   function PutAllDrivers(path:string;var resfile:TResourcefile;
  49.                          keep:boolean):integer;
  50.  
  51.   Puts all the standard drivers into the given resource file; assumes
  52.   that it can find them all in the given path (terminated with a
  53.   backslash, e.g. "c:\drivers\").  Returns all graphics error constants
  54.   from PutDriver or'd together.  I can't think of any use for the value,
  55.   other than to check for 0 or non-zero.
  56.  
  57.   procedure DelDriver(Graphdriver:integer;var resfile:TResourcefile);
  58.  
  59.   Deletes the driver with the given number from the resource file.
  60.   Numbers are those used by InitGraph, i.e. CGA=1, VGA=9, etc.  This
  61.   doesn't save any space; to recover the space from the deleted driver,
  62.   you need to pack the resource file.
  63.  
  64.   NB:  Some drivers handle several devices, so for example deleting VGA
  65.   will also take out EGA.  The standard list is:
  66.  
  67.          File          Graphdriver constants
  68.  
  69.          CGA.BGI:      CGA, MCGA
  70.          EGAVGA.BGI:   EGA, EGA64, EGAMono, VGA
  71.          IBM8514.BGI:  IBM8514
  72.          HERC.BGI:     HercMono
  73.          ATT.BGI:      ATT400
  74.          PC3270.BGI:   PC3270
  75.  
  76. Interfaced Types
  77.  
  78.   PResourcefile2 = ^TResourcefile2;
  79.   TResourcefile2 = object(TResourcefile)
  80.  
  81.   A resource file that knows how to pack itself.  The standard resource
  82.   files require you to fiddle around with Switchto, and generally sweat
  83.   a lot; this one has all that already done for you.  It needs temporary
  84.   space to work in, and will take RAM, EMS, XMS or disk, depending on
  85.   what's available, since it uses a TempStream from my Streams unit.
  86.   The downside of all this convenience is that it pulls in a fair bit of
  87.   code (about 4K) if you use Pack and don't use TempStream anywhere else.
  88.  
  89.   This really belongs in the Streams or Objects unit; it will be moved
  90.   there in future versions.
  91.  
  92.   Note:  If you don't have the Streams unit, you won't be able to compile
  93.   BGIRES as distributed; however, I've put in some conditional compiling
  94.   directives which will make it work if you define NOSTREAMS.
  95.  
  96.     procedure TResourceFile2.Pack;
  97.  
  98.     Packs in place.  This works even if the resource file is embedded in
  99.     a larger file, e.g. an .EXE file with overlays and resources.  Note
  100.     that whatever follows the resource file will be moved; something
  101.     like the overlay manager would need to be reinitialized afterwards.
  102.  
  103.  
  104.   PBGIDriver = ^TBGIDriver;
  105.   Tbgidriver = object(TObject)
  106.  
  107.   This object manages the memory used by the .BGI driver.  You probably
  108.   never need to use it yourself; the procedures and functions above do
  109.   everything necessary.  The fields and methods are commented in the
  110.   source.
  111.  
  112. Interfaced Constants
  113.  
  114.   All of the typed constants in BGIRES are declared in separate const
  115.   blocks.  This means that if you somehow don't need all of them, they
  116.   won't be linked into your final program.
  117.  
  118.   drivernum : array[1..10] of word = (0,0,1,1,1,2,3,4,1,5);
  119.  
  120.   These are the internal driver numbers for graphdriver values 1 to 10.
  121.   BGI files keep two sets of numbers:  the driver number (0 to 5 for the
  122.   standard ones), and the graphdriver values (1 to 10, i.e. CGA to
  123.   PC3270).  This array lets you do the translation.
  124.  
  125.   drivernames : array[0..5] of String[11] =
  126.    ('CGA.BGI', 'EGAVGA.BGI', 'IBM8514.BGI',
  127.     'HERC.BGI', 'ATT.BGI', 'PC3270.BGI');
  128.  
  129.   These are the filenames corresponding to the internal driver numbers.
  130.  
  131.   BGITypeCode = $4247;  { 'BG' }
  132.  
  133.   This is the object type code used within the resource file.  It may
  134.   collide with the object type code you choose for your own objects; if
  135.   so, you can change it to whatever you like.
  136.  
  137.   RBGIDriver : TStreamRec = ( blah blah blah );
  138.  
  139.   A stream registration record is set up to make registration easy.
  140.   Since there's not much use in using this unit without registering the
  141.   TBGIDriver type, it gets automatically registered in the startup code.
  142.  
  143. Examples
  144.  
  145.   Take a look through the sample code in Demo.pas.  This program does
  146.   the following:
  147.  
  148.     - it declares itself as the resource file
  149.     - if there aren't any .BGI drivers on the end of DEMO.EXE (as there
  150.     won't be on the first run through), it adds as many as it can find
  151.     in the path given on the command line
  152.     - it deletes all of them except the one corresponding to the current
  153.     video board, and shrinks itself back as much as possible.
  154.     - it gives a flashy ad for BGIRES, which is nearly readable, but
  155.     probably runs at the wrong speed on your machine.
  156.  
  157. License
  158.  
  159.   Hey, didn't you RTFM?  Up at the top, it says this is public domain.
  160.   I mean it:  it's free.  That's the good news.  The bad news, of
  161.   course, is that I can't guarantee that it'll work for you; for all I
  162.   know, it might make your monitor blow up (or as I read in a disclaimer
  163.   on Usenet the other day, turn your chair into antimatter :-).
  164.  
  165.   Still, if you do find any bugs, I'd like to hear about them.  Send me
  166.   mail, to one of the following addresses (in order of decreasing
  167.   stability):
  168.  
  169.     71631,122 on Compuserve
  170.  
  171.     337 Willingdon Ave., Kingston, Ontario, Canada
  172.  
  173.     DJ Murdoch at 1:249/1.5 on Fidonet
  174.  
  175.     dmurdoch@mast.queensu.ca on Internet
  176.  
  177.   Finally, if you have an overwhelming desire to pay for this software,
  178.   please donate $5 (or the equivalent in your local currency) to a local
  179.